\documentstyle[12pt,a4]{article}

\begin{document}
\title{JRTPLIB (v2.5) -  REFERENCE MANUAL}
\author{Jori Liesenborgs (jori@lumumba.luc.ac.be)}
\date{2nd December 2000}
\maketitle


\section{General Information}

\subsection{Description}

JRTPLIB (Jori's RTP Library) is an object oriented library for the use of RTP
(Real-Time Transport Protocol). Normally, it should follow the specifications
according to RFC 1889. This textfile describes the classes and functions 
which form the interface of the library. If some of the used terms aren't
clear, you should consult RFC 1889.

\subsection{Author \& contact}

The library was written completely from scratch by Jori Liesenborgs. Any
comments, bugreports, ideas for improvements,... can be sent to the following
e-mail address:	
	jori@lumumba.luc.ac.be

\subsection{Platforms}

The library uses the socket mechanism for network communications. This means
it can be compiled (perhaps with some minor modifications) and used on 
various platforms. It has been tested on a Linux platform and on a Windows
platform (using the Winsock library). It's also known to work on Solaris,
HP-UX, FreeBSD and VxWorks platforms.

\subsection{Important general information}

All of the functions with return type 'int', return 0 or more on success. 
Thus, with these functions an error is always indicated by a negative number.

\subsection{What the library doesn't do}

An important remark is that the library will not necessarily filter out 
duplicate packets. The packets from one sender which are in the received packets
queue after a call to 'Poll', won't be duplicates of other packets in the queue.
Once out of the queue, however, there is no guarantee that some accepted packet 
won't have been received already. 
There is a good reason for this: the application using the library probably has
more information about which packets are expected. Using this information it's 
possible to filter out duplicate packets using less memory than would be 
required inside the library.

\subsection{Copyright \& disclaimer}

  Permission is hereby granted, free of charge, to any person obtaining a
  copy of this software and associated documentation files (the "Software"),
  to deal in the Software without restriction, including without limitation
  the rights to use, copy, modify, merge, publish, distribute, sublicense,
  and/or sell copies of the Software, and to permit persons to whom the
  Software is furnished to do so, subject to the following conditions:\\

  The above copyright notice and this permission notice shall be included
  in all copies or substantial portions of the Software.\\

  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
  OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
  THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
  IN THE SOFTWARE.

\section{class RTPSession}

\subsection{Description}

This class is used to set up a RTP session.

\subsection{Member functions}

\begin{itemize}
\item {\tt int Create(int localportbase)}\\
	This function attempts to create a RTP session with a given portbase.
	It creates an initial timestamp and an initial packet sequence
	number. It also creates a local synchronization source identifier
	(SSRC). When doing this, the list of illegal SSRCs is checked. This
	list can be modified by the functions AddIllegalLocalSSRC,
	DeleteIllegalLocalSSRC and ClearInvalidLocalSSRCList. In a newly
	created session, there are no destinations to send the RTP and RTCP
	packets to. Destinations can be set by the functions AddDestination,
	DeleteDestination and ClearDestinations.

\item {\tt int GetPortBase()}\\
	Returns the portbase of this session.

\item {\tt int GetLocalSSRC(unsigned long *ssrc)}\\
	This function retrieves the local synchronization source identifier.

\item {\tt int Destroy()}\\
	Destroys the session. All info is destroyed, including destinations,
	default values for SendPacket, invalid local SSRC values,...	

\item {\tt int GetRTPSocket(RTPSOCKET *sock)}\\
	Retrieves the RTP socket (used for receiving RTP data). This way,
	the socket can be used outside the library. A practical use would be
	in the 'select' function.

\item {\tt int GetRTCPSocket(RTPSOCKET *sock)}\\
	Retrieves the RTCP socket (used for receiving RTCP data). This way,
	the socket can be used outside the library. A practical use would
	be in the 'select' function.

\item {\tt int GetSendSocket(RTPSOCKET *sock)}\\
	Retrieves the socket which is used for sending the RTP data. This
	way, the socket can be used outside the library. A practical use
	would be in the 'select' function.

\item {\tt int GetSendPort()}\\
	Retrieves the port to which the sending socket was bound.

\item {\tt int GetLocalIP(unsigned long *ip)}\\
 	Puts the local IP address which is used by the library in 'ip'.

\item {\tt int SetToS(int tos)}\\
 	Set the IP type of service (ToS) field for outgoing RTP and RTCP
	packets.
 
\item {\tt int AddDestination(unsigned long remoteIP,int remoteportbase)}\\
 	Adds a destination to send RTP and RTCP data to.

\item {\tt int DeleteDestination(unsigned long remoteIP,int remoteportbase)}\\
	Deletes a destination from the list of destinations.
	
\item {\tt void ClearDestinations()}\\
	Clears the list of destinations.

\item {\tt bool SupportsMulticasting()}\\
	Returns 'true' if the library is compiled with multicasting support,
	otherwise the function returns 'false'.

\item {\tt int JoinMulticastGroup(unsigned long mcastIP)}\\
 	This function attempts to join the multicast group specified by the
 	address in 'mcastIP'. Note that you only have to join a multicast
 	group to receive packets which are sent to it. You don't have to be
 	in a group to send packets to it.

\item {\tt int LeaveMulticastGroup(unsigned long mcastIP)}\\
 	This function attempts to leave the multicast group specified by the
 	address in 'mcastIP'

\item {\tt void LeaveAllMulticastGroups()}\\
 	Leaves all multicast groups to which the session was previously joined
 	through the use of JoinMulticastGroup
 	
\item {\tt int SetMulticastTTL(unsigned char ttl)}\\
 	Use this function to change the Time To Live (TTL) field for multicast
 	packets. The TTL field is a field in the IP header which determines
 	the lifetime for a packet (normally, this the maximum number of hops
 	for a packet).
	
\item {\tt int SendPacket(void *data,int len)}\\
	Sends a RTP packet with a payload containing of 'len' bytes of
	'data'. To be able to use this function, you must first set the
	default values for the payload type, the mark bit and the timestamp
	increment value. These default values can be set with the functions
	SetDefaultPayloadType, SetDefaultMark and SetDefaultTimeStampIncrement.

\item {\tt int SendPacket(void *data,int len,unsigned char pt,bool mark,unsigned long timestampinc)}\\
	Sends a RTP packet with a payload containing of 'len' bytes of
	'data'. The packet type is specified by 'pt', the mark bit by 'mark'
	and the timestamp increment by 'timestampinc'. The values set by
	SetDefaultPayloadType, SetDefaultMark and SetDefaultTimeStampIncrement
	are ignored.
	
\item {\tt int SendPacket(void *data,int len,unsigned short hdrextID,void *hdrextdata,int numhdrextwords)}\\
	Sends a RTP packet with a payload containing of 'len' bytes of
	'data'. To be able to use this function, you must first set the
	default values for the payload type, the mark bit and the timestamp
	increment value. These default values can be set with the functions
	SetDefaultPayloadType, SetDefaultMark and SetDefaultTimeStampIncrement.
	This function also causes a RTP header extension to be included in the
	packet. This extension has identifier 'hdrextID' and the length of the
	extension data is specified in 32-bit words by 'numhdrextwords'. The
	data itself is contained in 'hdrextdata'.

\item {\tt int SendPacket(void *data,int len,unsigned char pt,bool mark,unsigned long timestampinc,unsigned short hdrextID,void *hdrextdata,int numhdrextwords)}\\
	Sends a RTP packet with a payload containing of 'len' bytes of
	'data'. The packet type is specified by 'pt', the mark bit by 'mark'
	and the timestamp increment by 'timestampinc'. The values set by
	SetDefaultPayloadType, SetDefaultMark and SetDefaultTimeStampIncrement
	are ignored. This function also causes a RTP header extension to be
	included in the packet. This extension has identifier 'hdrextID' and
	the length of the extension data is specified in 32-bit words by
	'numhdrextwords'. The data itself is contained in 'hdrextdata'.

\item {\tt void SetDefaultPayloadType(unsigned char pt)}\\
	Sets the default packet type.

\item {\tt void SetDefaultMark(bool mark)}\\
	Sets the default value for the mark bit.

\item {\tt void SetDefaultTimeStampIncrement(unsigned long inc)}\\
	Sets the default timestamp increment value.

\item {\tt int IncrementTimeStamp(unsigned long inc)}\\
	Increments the current timestamp with value 'inc'.

\item {\tt int IncrementTimeStampDefault()}\\
	Increments the current timestamp with the default value, set by the
	function SetDefaultTimeStampIncrement.

\item {\tt int PollData()}\\
	Checks for data on RTP and RTCP ports. If any data is present, it's
	immediately processed. To retrieve RTP packets or info gathered from
	RTCP packets, you can use the functions GotoFirstSource, GotoNextSource,
	GotoFirstSourceWithData, GotoNextSourceWithData, GetNextPacket,
	GetCurrentSourceInfo and GetSourceInfo. After calling PollData, you
	should always use one of the GotoFirst functions before one of the
	GotoNext functions, as the list of participating sources may have
	changed: sources could have joined the session or may have left the
	session.
	Note that currently own RTCP packets are always discarded.

\item {\tt bool GotoFirstSource()}\\
	This function goes sets a pointer to the first participating source.
	You can use this function to start an iteration over the participating
	sources. It returns 'true' if there are any participating sources,
	otherwise the function returns 'false'.
	
\item {\tt bool GotoNextSource()}\\
	You can use this function to iterate over the participating sources.
	If there is a source that hasn't been processed yet, the function
	returns 'true'. If all sources were covered, 'false' is returned.

\item {\tt bool GotoFirstSourceWithData()}\\
	This function is similar to GotoFirstSource, but it skips sources
	that haven't got any data pending on their input queues. Returns
	'true' is a source with data on its queue exists. Returns 'false'
	otherwise.

\item {\tt bool GotoNextSourceWithData()}\\
	This function is similar to GotoNextSource, but it skips sources
	that haven't got any data pending on their input queues. If there
	aren't any sources left to process 'false' is returned. If another
	source was found, 'true' is returned.

\item {\tt RTPPacket *GetNextPacket()}\\
	When iterating over the participating sources with GotoFirst and
	GotoNext functions, you can use this function to extract a packet
	from the current source's queue. If data is available, the function
	returns an instance of the class RTPPacket containing the data.
	Otherwise, NULL is returned. If a packet is returned, it must be
	destroyed by a call to 'delete' when it is no longer needed.

\item {\tt RTPSourceData *GetCurrentSourceInfo()}\\
	When iterating over the participating sources with GotoFirst and
	GotoNext functions, you can use this function to get information
	about the current source. If the iteration has stopped NULL is
	returned, otherwise the function returns an instance of the class
	RTPSourceData containing the info about the current source.

\item {\tt RTPSourceData *GetSourceInfo(unsigned long ssrc)}\\
	Retrieves information about the participating source with
	synchronization source identifier 'ssrc'. If there is an entry for
	that source, an instance of the class RTPSourceData is returned.
	Otherwise the function returns NULL.

\item {\tt AddInvalidLocalSSRC(unsigned long ssrc)}\\
	Adds the synchronization source identifier 'ssrc' to the list of
	invalid local sychronization source identifiers. This list is checked
	when the local SSRC identifier is created.

\item {\tt int RemoveInvalidLocalSSRC(unsigned long ssrc)}\\
	Removes an entry from the list of invalid local SSRCs.

\item {\tt void ClearInvalidLocalSSRCList()}\\
	Clears the list of invalid local SSRCs.

\item {\tt int AddCSRC(unsigned long csrc)}\\
	Adds an entry to the list of contributing sources. Info about these
	sources can be set with SetCSRC functions.

\item {\tt int DeleteCSRC(unsigned long csrc)}\\
	Deletes an entry from the list of contributing sources.

\item {\tt void ClearCSRCList()}\\
	Clears the list of contributing sources.

\item {\tt int SetReceiveMode(int mode)}\\
	Sets the receive mode. The parameter 'mode' has three legal values:
	\begin{itemize}
	\item RECEIVEMODE\_ALL \\
		Accept all incoming data on RTP and RTCP ports.
	\item RECEIVEMODE\_IGNORESOME \\
		Ignore packets from the ip-port pairs in the ignore list, but
		accept all other packets.		
	\item RECEIVEMODE\_ACCEPTSOME \\
		Ignore all packets, except those whose ip-port origin is
		found in the accept list.
	\end{itemize}
	The ignore list can be modified with the function AddToIgnoreList,
	DeleteFromIgnoreList and ClearIgnoreList. The accept list can be
	modified with AddToAcceptList, DeleteFromAcceptList and
	ClearAcceptList.
		
\item {\tt int AddToIgnoreList(unsigned long remoteIP,bool allports,int portbase)}\\
	Adds an origin to the ignore list. If 'allports' is true, all
	data from address 'remoteIP' is ignored, no matter what port it
	came from. This function will have no noticable effect until the
	receive mode is set to RECEIVEMODE\_IGNORESOME.

\item {\tt int DeleteFromIgnoreList(unsigned long remoteIP,bool allports,int portbase)}\\
	Deletes an entry from the ignore list with the specified parameters.
	
\item {\tt void ClearIgnoreList()}
	Clears the ignore list.

\item {\tt int AddToAcceptList(unsigned long remoteIP,bool allports,int portbase)}\\
	Adds an origin to the accept list. If 'allports' is true, all
	data from address 'remoteIP' is accepted, no matter what port it
	came from. This function will have no noticable effect until the
	receive mode is set to RECEIVEMODE\_ACCEPTSOME.

\item {\tt int DeleteFromAcceptList(unsigned long remoteIP,bool allports,int portbase)}\\
	Deletes an entry with the specified parameters from the accept list.

\item {\tt void ClearAcceptList()}\\
	Clears the accept list.

\item {\tt int SetMaxPacketSize(int m)}\\
	Sets the maximum size that a RTP or RTCP packet can have. This size
	does not include IP or UDP header sizes. It defaults to 1100.

\item {\tt void SetSessionBandwidth(double bw)}\\
	Sets the bandwidth the session is supposed to use. The parameter
	is treated in units of bits per second (bps). This value is used to
	calculate the interval at which RTCP packets should be sent. The
	default value is 64000 bps.	
	
\item {\tt void SetTimestampUnit(double t)}\\
	Sets the value in seconds to which one timestamp unit corresponds.
	The default is 1/8000 sec.

\item {\tt void SetControlTrafficFragment(double frag)}\\
	Sets the fragment of the session bandwidth that the RTCP packets
	may occupy. This value is used to calculate the the interval at
	which RTCP packets should be sent. The default value is 5/100.
	
\item {\tt int SetLocalName(char *s,int len)}\\
	Sets the name of the local participant. The name is specified in
	parameter 's' and has length 'len'.
	
\item {\tt int SetLocalEMail(char *s,int len)}\\
	Sets the e-mail address of the local participant. The address is
	specified in parameter 's' and has length 'len'.

\item {\tt int SetLocalLocation(char *s,int len)}\\
	Sets the location of the local participant. The location is specified
	in parameter 's' and has length 'len'.

\item {\tt int SetLocalPhone(char *s,int len)}\\
	Sets the telephone number of the local participant. The number is
	specified in parameter 's' and has length 'len'.

\item {\tt int SetLocalTool(char *s,int len)}\\
	Sets the tool name for the local participant. The tool is specified
	in parameter 's' and has length 'len'.

\item {\tt int SetLocalNote(char *s,int len)}\\
	Sets a note for the local participant. The note is specified in
	parameter 's' and has length 'len'.

\item {\tt int SetCSRC\_CNAME(unsigned long csrc,char *s,int len)}\\
	Sets the canonical name (CNAME) for the contributing source with
	identifier 'csrc'. The name is specified by 's' and has length 'len'.

\item {\tt int SetCSRCName(unsigned long csrc,char *s,int len)}\\
	Sets the name for the contributing source with identifier 'csrc'.
	The name is specified by 's' and has length 'len'.

\item {\tt int SetCSRCEMail(unsigned long csrc,char *s,int len)}\\
	Sets the e-mail address for the contributing source with identifier
	'csrc'.	The address is specified by 's' and has length 'len'.

\item {\tt int SetCSRCLocation(unsigned long csrc,char *s,int len)}\\
	Sets the location for the contributing source with identifier 'csrc'.
	The location is specified by 's' and has length 'len'.

\item {\tt int SetCSRCPhone(unsigned long csrc,char *s,int len)}\\
	Sets the telephone number for the contributing source with identifier
	'csrc'.	The number is specified by 's' and has length 'len'.

\item {\tt int SetCSRCTool(unsigned long csrc,char *s,int len)}\\
	Specifies a tool for the contributing source with identifier 'csrc'.
	The tool name is specified by 's' and has length 'len'.

\item {\tt int SetCSRCNote(unsigned long csrc,char *s,int len)}\\
	Sets a note for the contributing source with identifier 'csrc'.	The
	note is specified by 's' and has length 'len'.

\item {\tt void EnableSendName(bool val)}\\
	Specifies if the name (either local or for a CSRC) should be sent
	to other participants.
	
\item {\tt void EnableSendEMail(bool val)}\\
	Specifies if the e-mail address (either local or for a CSRC) should
	be sent to other participants.
	
\item {\tt void EnableSendLocation(bool val)}\\
	Specifies if the location (either local or for a CSRC) should be
	sent to other participants.
	
\item {\tt void EnableSendPhone(bool val)}\\
	Specifies if the phone number (either local or for a CSRC) should be
	sent to other participants.
	
\item {\tt void EnableSendTool(bool val)}\\
	Specifies if tool information (either local or from a CSRC) should
	be sent	to other participants.
	
\item {\tt void EnableSendNote(bool val)}\\
	Specifies if notes (either local or from a CSRC) should be sent
	to other participants.
	
\item {\tt void SetLocalSSRCCollisionHandler(RTPExceptionHandler handler,void *usrdata)}\\
	Sets the handler for collisions with the local SSRC identifier. The
	parameter 'usrdata' will be passed when calling this handler. Set the
	handler to NULL to disable.

\item {\tt void SetSSRCCollisionHandler(RTPExceptionHandler handler,void *usrdata)}\\
	Sets the handler for collisions between SSRC identifiers, other than
	the local SSRC identifier. The parameter 'usrdata' will be passed
	when calling this handler. Set the handler to NULL to disable.

\item {\tt void SetNewSourceHandler(RTPExceptionHandler handler,void *usrdata)}\\
	Sets the handler to call when a source has joined the session. The
	parameter 'usrdata' will be passed when calling this handler. Set the
	handler to NULL to disable.

\item {\tt void SetInvalidSDESTypeHandler(RTPExceptionHandler handler,void *usrdata)}\\
	Sets the handler that will be called when a RTCP packet with an illegal
	SDES type arrives. The parameter 'usrdata' will be passed when calling
	this handler. Set the handler to NULL to disable.

\item {\tt void SetSSRCDepartureHandler(RTPExceptionHandler handler,void *usrdata)}\\
	Sets the handler to call when a source leaves the session. The
	parameter 'usrdata' will be passed when calling this handler. Set the
	handler to NULL to disable.
	
\item {\tt void SetSSRCTimeoutHandler(RTPExceptionHandler handler,void *usrdata)}\\
	Sets the handler to call when a source leaves the session due to a
	timeout. The parameter 'usrdata' will be passed when calling this
	handler. Set the handler to NULL to disable.

\item {\tt void SetReceiveRTCPAPPHandler(RTPExceptionHandler handler,void *usrdata)}\\
	Sets the handler to call when application specific data arrives. The
	parameter 'usrdata' will be passed when calling this handler. Set the
	handler to NULL to disable.

\item {\tt void SetTransmitRTCPAPPHandler(RTPExceptionHandler handler,void *usrdata)}\\
	Sets the handler to call when the library will send RTCP data. Using
	this handler you can then pass application specific data to be included
	in the RTCP packet. The parameter 'usrdata' will be passed when calling
	this handler. Set the handler to NULL to disable.

\item {\tt void SetRTCPPacketHandler(RTPExceptionHandler handler,void *usrdata)}\\
 	Sets the handler to be called for each incoming RTCP packet (also
 	invalid ones!). The parameter 'usrdata' will be passed when calling
 	this handler. Set the handler to NULL to disable.
	
\item {\tt void ClearHandlers()}\\
	Clears all handlers.

\item {\tt void SetAcceptOwnPackets(bool accept)}\\
	Specifies if received packets which originated from your own session
	should be accepted or discarded. Accepting them can be useful for
	debugging purposes: you can make the session send packets to itself.
	By default, the packets are discarded. Note that own RTCP packets
	currently are always discarded.

\item {\tt bool GetAcceptOwnPackets()}\\
	Returns true if own packets are accepted, false otherwise.

\end{itemize}
	

\section{class RTPPacket}

\subsection{Description}

Instances of this class contain RTP packet data. They are returned by a call
to the member function GetNextPacket of the class RTPSession or by a call to
the member function ExtractPacket of the class RTPSourceData.

\subsection{Member functions}
\begin{itemize}

\item {\tt unsigned long GetSSRC()}\\
	Gets the synchronization source identifier from the origin of this
	packet.

\item {\tt unsigned long GetExtendedSequenceNumber()}\\
	Gets the extended sequence number of the packet. Note that the
	sequence numbers start from a random offset, as speficied in RFC 1889.

\item {\tt unsigned long GetTimeStamp()}\\
	Gets the timestamp of the packet. The timestamp starts at a random
	offset.

\item {\tt int GetPayloadLength()}\\
	Gets the length of the payload (the actual data contained in the
	RTP packet)

\item {\tt unsigned char *GetRawPacket()}\\
	Returns a pointer to the raw packet data.

\item {\tt unsigned char *GetPayload()}\\
	Returns a pointer to the payload, the actual data of the RTP packet.

\item {\tt unsigned char GetPayloadType()}\\
 	Returns the payload type of the packet.

\item {\tt bool IsMarked()}\\
 	Returns 'true' if the marker bit in the RTP header was set, 'false'
 	otherwise.
 	
\item {\tt int GetNumberOfCSRCs()}\\
 	Returns the number of CSRC identifiers contained in the packet.
 	
\item {\tt unsigned long GetCSRC(int pos)}\\
 	Returns a CSRC identifier which was contained in the packet. 'pos'
 	is valid if it is greater or equal to zero and smaller than the
 	value returned by a call to 'GetNumberOfCSRCs'.

\item {\tt bool HasHeaderExtension()}\\
 	Returns 'true' if the RTP packet has a header extension, 'false'
 	otherwise.

\item {\tt unsigned short GetHeaderExtensionID()}\\
	If the packet has a header extension, this function returns the
	identifier of the header extension.

\item {\tt int GetHeaderExtensionLength()}\\
 	Returns the length, in number of bytes, of the header extension
 	data.

\item {\tt unsigned char *GetHeaderExtensionData()}\\
 	Returns the data contained in the header extension.


\end{itemize}
 	

\section{class RTPSourceData}

\subsection{Description}

This class contains information about a participating source. A packet that
is returned by the member functions GetCurrentSourceInfo or GetSourceInfo
of the class RTPSession, must NOT be deleted.

\subsection{Member functions}

\begin{itemize}

\item {\tt RTPPacket *ExtractPacket()}\\
	Extracts a packet from the packet queue of this source. If no packets
	are available, NULL is returned. If a packet is returned, it must be
	destroyed by a call to 'delete' when it is no longer needed.

\item {\tt void FlushPackets()}\\
	Deletes all pending packets on the queue.

\item {\tt unsigned long GetSSRC()}\\
	Returns the synchronization source identifier of this source.

\item {\tt bool HasData()}\\
	Returns 'true' if there are any packets on the packet queue. Otherwise
	'false' is returned.

\item {\tt void SetTimestampUnit(double tsunit)}\\
 	Sets the timestamp unit for the RTP packets coming from this source.

\item {\tt double GetTimestampUnit()}\\
	Retrieves the value of the timestamp unit which is used for calculations
	involving this source. When a new source had joined in, its timestamp
	unit is initialized to that of the local session.
	
\item {\tt bool SR\_HasInfo()}\\
	Returns 'true' if there were sender reports received from this
	source. If the participating source is not a sender of RTP data,
	this will always return 'false'.

\item {\tt void SR\_GetNTPTimestamp(unsigned long *msw,unsigned long *lsw)}\\
	Gets the NTP timestamp that was specified in the last received
	sender report.

\item {\tt unsigned long SR\_GetRTPTimestamp()}\\
	Gets the timestamp that was last mentioned in a sender report.

\item {\tt unsigned long SR\_GetPacketCount()}\\
	Gets the packet count of this source according to the information
	from the last sender report.

\item {\tt unsigned long SR\_GetByteCount()}\\
	Gets the byte (octet) count of this source according to the
	information from the last sender report.

\item {\tt struct timeval SR\_GetReceiveTime()}\\
 	This returns the time when the last sender report was received. You
 	can use the 'getntptime' function to transform this value into NTP
 	time format, but be careful: this function returns values in network
 	byte order!

\item {\tt bool RR\_HasInfo()}\\
	Returns 'true' if the source has sent any receiver reports about
	the local source. Otherwise it returns false.

\item {\tt float RR\_GetFractionLost()}\\
	Gets the fraction of lost packets which originated from this source.
	This value is calculated from receiver reports.

\item {\tt long RR\_GetPacketsLost()}\\
	Gets the number of lost packets which originated from this source.
	This value is read from receiver reports.
	
\item {\tt unsigned long RR\_GetExtendedHighestSequenceNumber()}\\
	Gets the extended highest sequence number of the packets that this
	source received from the local source. Its value is read from
	receiver reports.

\item {\tt unsigned long RR\_GetJitter()}\\
	Returns the amount of jitter in timestamp units that this source
	noticed when receiving packets from the local source. The value is
	read from receiver reports.

\item {\tt unsigned long RR\_GetLastSRTimestamp()}\\
	Returns the time at which the current source received the last
	sender report from the local source. The high 16 bits are in fact
	the low 16 bits of the most significant 32 bit word of the NTP
	timestamp. The low 16 bits are the high 16 bits of the fractional
	part (32 bits) of the NTP timestamp. So this value is in fact the
	middle 32 bits of the whole 64 bit NTP timestamp. If no sender
	reports were received, the value is zero.

\item {\tt unsigned long RR\_GetDelaySinceLastSR()}\\
	Returns the time that has elapsed since the current source received
	a sender report from the local source. The value is given in
	1/65536 seconds. If no sender reports were received, the value is
	zero.

\item {\tt struct timeval RR\_GetReceiveTime()}\\
 	This returns the time when the last receiver report was received. You
 	can use the 'getntptime' function to transform this value into NTP
 	time format, but be careful: this function returns values in network
 	byte order!
 	
\item {\tt bool INF\_HasSentData()}\\
	Returns 'true' if the current source has sent RTP data. Otherwise
	the function returns 'false'.

\item {\tt long INF\_GetNumPacketsReceived()}\\
	Returns the number of packets received from this source.

\item {\tt unsigned long INF\_GetBaseSequenceNumber()}\\
	The sequence number of RTP packets starts at a random offset. This
	function returns this base sequence number. It is just the lowest
	extended sequence number that was present in RTP packets.

\item {\tt unsigned long INF\_GetExtendedHighestSequenceNumber()}\\
	Returns the extended highest sequence number received from this
	source.
	
\item {\tt unsigned long INF\_GetJitter()}\\
	Returns the amount of jitter in timestamp units that the local
	source noticed when receiving packets from this source.
	
\item {\tt struct timeval INF\_GetRoundTripTime()}\\
	This function gives an approximation of the round-trip-time, as
	suggested in RFC 1889.

\item {\tt char *SDES\_GetCNAME(int *len)}\\
	Returns the CNAME (canonical name) of this source. The length is
	set in 'len'.

\item {\tt char *SDES\_GetName(int *len)}\\
	Returns the name of this source. The length is set in 'len'.

\item {\tt char *SDES\_GetEMail(int *len)}\\
	Returns the email address of this source. The length is set in 'len'.

\item {\tt char *SDES\_GetLocation(int *len)}\\
	Returns the location of this source. The length is set in 'len'.

\item {\tt char *SDES\_GetPhone(int *len)}\\
	Returns the phone number for this source. The length is set in 'len'.

\item {\tt char *SDES\_GetTool(int *len)}\\
	Returns tool information for this source. The length is set in 'len'.

\item {\tt char *SDES\_GetNote(int *len)}\\
	Returns a note from this source. The length is set in 'len'.

\end{itemize}


\section{Exception handlers}

\subsection{Description}

In the class RTPSession, you can set exception handlers for various types
of events. If you look at those functions in the class description, you will
see that all of these function take a parameter of type RTPExceptionHandler
and a paramater of type void (the so called 'usrdata' parameter). The
parameter of type RTPExceptionHandler should be a function with the following
format:\\
\\
{\tt void MyHandler(int exceptiontype,void *exceptiondata,void *usrdata)}\\
\\
You may also use the value NULL for this parameter. In this case, the handler
will be disabled. The parameter 'usrdata' is the pointer that was specified
when the handler was set. The contents of 'exceptiondata' will differ
according to the type of event that has occurred. The possibilities will
be discussed below, together with the possible exception types.

\subsection{Exception types}

When the handler is called, the parameter 'exceptiontype' contains the type
of event that has occurred. These are the posible values:
\begin{itemize}
	\item RTP\_EXCEPTION\_LOCALSSRCCOLLISION\\
		There has been a collision with the local synchronization
		source identifier. The parameter 'exceptiondata' is of type
		RTPExcepSSRCCollision. For a description of the contents,
		see the part about the exception structures.		
	\item RTP\_EXCEPTION\_SSRCCOLLISION\\
		There has been a collision between synchronization source
		identifiers, other than the local identifier. The parameter
		'exceptiondata' is of type RTPExcepSSRCCollision. For a
		description of the contents, see the part about the exception
		structures.		
	\item RTP\_EXCEPTION\_NEWSOURCE\\
		A new source has joined the session. The 'exceptiondata'
		parameter is of type RTPExcepSSRC. For a description of the
		contents, see the part about the exception structures.
	\item RTP\_EXCEPTION\_INVALIDSDESTYPE\\
		A RTCP packet containing an invalid SDES type has arrived. The
		parameter 'exceptiondata' is of type RTPExcepInvalSDESType. For
		a description of the contents, see the part about the exception
		structures.
	\item RTP\_EXCEPTION\_SSRCDEPARTURE\\
		A certain source has left the session. The 'exceptiondata'
		parameter is of type RTPExcepSSRC. For a description of the
		contents, see the part about the exception structures.
	\item RTP\_EXCEPTION\_SSRCTIMEOUT\\
		A certain source has left the session due to a timeout. The
		'exceptiondata' parameter is of type RTPExcepSSRC. For a
		description of the contents, see the part about the exception
		structures.
	\item RTP\_EXCEPTION\_RECEIVERTCPAPPDATA\\
		Application specific data has arrived. The parameter
		'exceptiondata' is of type RTPExcepAppData. For a description
		of the contents, see the part about the exception structures.
	\item RTP\_EXCEPTION\_TRANSMITRTCPAPPDATA\\
		The library asks for application specific data. The parameter
		'exceptiondata' is of type RTPExcepAppData. For a description
		of the contents, see the part about the exception structures.
	\item RTP\_EXCEPTION\_RTCPPACKET\\
		If this handler is enabled, your handler will be called for
		each received RTCP packet. This way, you can examine the raw
		RTCP data yourself if necessary. The parameter 'exceptiondata'
		is of type RTPExcepRTCPPacket. For a description of the
		contents, see the part about the exception structures.
	\end{itemize}
	
\subsection{Structures}

The data that is specified in the parameter 'exceptiondata' is contained in
one of the structures that will be described here. If you want to save the
data, you must make a copy of it somehow, and not just save a pointer to it,
as the data may be altered or deleted after the handler is called. The used
structures are these:
\begin{itemize}

\item {\tt RTPExcepSSRCCollision}\\
	This structure has the following members:
		\begin{itemize}
		
		\item {\tt unsigned long ssrc}\\
			The synchronization source identifier of the colliding
			sources.
		\item {\tt unsigned long ip}\\
			The IP address of the source that caused the collision.
		\item {\tt bool rtpdata}\\
			This member is 'true' if the collision occurred when
			processing RTP data. It is false if it happened while
			processing RTCP data.
		\item {\tt int port}\\
			The port from which the RTP or RTCP data originated.
		\end{itemize}
		
\item {\tt RTPExcepSSRC}\\
	The structure has only one member:
		\begin{itemize}
		\item {\tt unsigned long ssrc}\\
			The sychronization source identifier of a certain source.
		\end{itemize}

\item {\tt RTPExcepInvalSDESType}\\
	The structure has the following members:
		\begin{itemize}
		\item {\tt unsigned long ssrc}\\
			The syncronization source identifier of the source to
			which the source description data belongs.
		\item {\tt int sdestype}\\
			The number of the type that was specified.
		\item {\tt unsigned char *sdesdata}\\
			A pointer to the source description data. The data does
			not include the SDES header.
		\item {\tt int datalen}\\
			The length of the data, in bytes.
		\end{itemize}
		
\item {\tt RTPExcepAppData}\\
	The structure has the following members:
		\begin{itemize}
		\item {\tt unsigned char subtype}\\
			Contains the subtype of the application specific data.
		\item {\tt unsigned long src}\\
			Contains the SSRC or CSRC identifier to which this
			data is relevant.
		\item {\tt unsigned char name[4]}\\
			Specifies a user defined name for this data.
		\item {\tt unsigned char *data}\\
			The data itself.
		\item {\tt int numwords}\\
			The length of the data, specified in 32-bit words.
		\item {\tt bool validdata}\\
			Specifies if the data is valid; only used when the
			library asks for application specific data to send.
		\item {\tt int prevreturnval}\\
			When passing application specific data to the library,
			the library uses this member to tell the handler if
			the previous data was handled correctly. A negative
			value indicates an error.
		\end{itemize}
	Here are some notes about sending and receiving application specific data.
	\begin{itemize}
	\item {\it Receiving application specific data:}\\
		For each RTCP application specific data block, the library
		will call the appropriate handler and will pass an instance
		of the RTPExcepAppData structure. Members 'validdata' and
		'prevreturnval' are not used. The members are in host byte
		order. The data, however, is passed in the exact way as it
		arrived, without doing any conversions (which would be
		impossible anyway, since the library does not know about
		the meaning of that data).
		
	\item {\it Sending application specific data:}\\
		When the handler for sending application specific RTCP data
		has been set, this handler will be called by the library when
		RTCP packets are generated. The library will pass an instance
		of the RTPExcepAppData structure, which the application can
		fill in to specify the data to send. Each time RTCP packets
		are generated, the library will keep calling this handler
		until the RTPExcepAppData member 'validdata' is set to
		'false'. When this is the case, the rest of the structure is
		ignored, so only set it to 'false' when all the application
		specific data has already been sent. The 'prevreturnval'
		indicates if there was an error with the previous data.
		The library sets default values for several members:
		\begin{tabbing}
		0123456701234567\=0123456701234567\kill
			subtype \> 0\\
			src \> own SSRC\\
			name \> four spaces\\
			data \> NULL\\
			numwords \> 0\\
			validdata \> false\\
		\end{tabbing}
		The members should be supplied in host byte order, the library
		will do the necessary conversions. However, the data is passed
		exactly as it was received, since the library can't possibly
		know how to interpret that data.
	\end{itemize}
\item {\tt RTPExcepRTCPPacket}\\
 	The structure has four members:
		\begin{itemize}
		\item {\tt unsigned char *packet}\\
			The raw RTCP packet data. No conversions were done, so
			you'll have to take the endianness into account if you
			want to process the data.
		\item {\tt int packetlen}\\
			The length of the RTCP packet.
		\item {\tt unsigned long sourceip}\\
			The IP address of the sender of the packet.
		\item {\tt int sourceport}\\
			The port from which this packet was sent.
		\end{itemize}

\end{itemize}

\end{document}
